---
title: クイックスタート
description: Build your first realtime voice assistant using the OpenAI Agents SDK in minutes.
---

import { Steps, Aside, Code } from '@astrojs/starlight/components';
import helloWorldExample from '../../../../../../../examples/docs/voice-agents/helloWorld.ts?raw';
import createAgentExample from '../../../../../../../examples/docs/voice-agents/createAgent.ts?raw';
import multiAgentsExample from '../../../../../../../examples/docs/voice-agents/multiAgents.ts?raw';
import createSessionExample from '../../../../../../../examples/docs/voice-agents/createSession.ts?raw';
import configureSessionExample from '../../../../../../../examples/docs/voice-agents/configureSession.ts?raw';
import handleAudioExample from '../../../../../../../examples/docs/voice-agents/handleAudio.ts?raw';
import defineToolExample from '../../../../../../../examples/docs/voice-agents/defineTool.ts?raw';
import toolApprovalEventExample from '../../../../../../../examples/docs/voice-agents/toolApprovalEvent.ts?raw';
import guardrailsExample from '../../../../../../../examples/docs/voice-agents/guardrails.ts?raw';
import guardrailSettingsExample from '../../../../../../../examples/docs/voice-agents/guardrailSettings.ts?raw';
import audioInterruptedExample from '../../../../../../../examples/docs/voice-agents/audioInterrupted.ts?raw';
import sessionInterruptExample from '../../../../../../../examples/docs/voice-agents/sessionInterrupt.ts?raw';
import sessionHistoryExample from '../../../../../../../examples/docs/voice-agents/sessionHistory.ts?raw';
import historyUpdatedExample from '../../../../../../../examples/docs/voice-agents/historyUpdated.ts?raw';
import updateHistoryExample from '../../../../../../../examples/docs/voice-agents/updateHistory.ts?raw';
import customWebRTCTransportExample from '../../../../../../../examples/docs/voice-agents/customWebRTCTransport.ts?raw';
import websocketSessionExample from '../../../../../../../examples/docs/voice-agents/websocketSession.ts?raw';
import transportEventsExample from '../../../../../../../examples/docs/voice-agents/transportEvents.ts?raw';
import thinClientExample from '../../../../../../../examples/docs/voice-agents/thinClient.ts?raw';

<Steps>

0. **プロジェクトの作成**

   このクイックスタートでは、ブラウザで使える音声エージェントを作成します。新しいプロジェクトを試したい場合は、[`Next.js`](https://nextjs.org/docs/getting-started/installation) または [`Vite`](https://vite.dev/guide/installation.html) をお試しください。

   ```bash
   npm create vite@latest my-project -- --template vanilla-ts
   ```

1. **Agents SDK のインストール**

   ```bash
   npm install @openai/agents zod@3
   ```

   代わりに、スタンドアロンのブラウザ向けパッケージである `@openai/agents-realtime` をインストールすることもできます。

2. **クライアントのエフェメラルトークンを生成する**

   このアプリケーションは ユーザー のブラウザで動作するため、Realtime API を介してモデルに安全に接続する方法が必要です。そのために、バックエンド サーバー で生成する [ephemeral client key](https://platform.openai.com/docs/guides/realtime#creating-an-ephemeral-token) を使用できます。テスト目的では、`curl` と通常の OpenAI API キーを使ってキーを生成することもできます。

   ```bash
   export OPENAI_API_KEY="sk-proj-...(your own key here)"
   curl -X POST https://api.openai.com/v1/realtime/client_secrets \
      -H "Authorization: Bearer $OPENAI_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "session": {
          "type": "realtime",
          "model": "gpt-realtime"
        }
      }'
   ```

   レスポンスにはトップレベルに "value" 文字列が含まれ、"ek\_" プレフィックスで始まります。このエフェメラルキーを使って後で WebRTC 接続を確立できます。このキーは短期間のみ有効で、再生成が必要になる点に注意してください。

3. **はじめてのエージェントの作成**

   新しい [`RealtimeAgent`](/openai-agents-js/openai/agents-realtime/classes/realtimeagent/) の作成は、通常の [`エージェント`](/openai-agents-js/ja/guides/agents) の作成と非常によく似ています。

   ```typescript
   import { RealtimeAgent } from '@openai/agents/realtime';

   const agent = new RealtimeAgent({
     name: 'Assistant',
     instructions: 'You are a helpful assistant.',
   });
   ```

4. **セッションの作成**

   通常のエージェントと異なり、音声エージェントは会話とモデルへの接続を継続的に処理する `RealtimeSession` 内で常時実行・リスニングします。このセッションは、音声の処理、中断、その他多くのライフサイクル機能も扱います。これらは後ほど説明します。

   ```typescript
   import { RealtimeSession } from '@openai/agents/realtime';

   const session = new RealtimeSession(agent, {
     model: 'gpt-realtime',
   });
   ```

   `RealtimeSession` のコンストラクタは最初の引数として `agent` を取ります。このエージェントが、 ユーザー が最初に対話できるエージェントになります。

5. **セッションへの接続**

   セッションに接続するには、先ほど生成したクライアントのエフェメラルトークンを渡す必要があります。

   ```typescript
   await session.connect({ apiKey: 'ek_...(put your own key here)' });
   ```

   これにより、ブラウザで WebRTC を使用して Realtime API に接続し、音声の入出力用にマイクとスピーカーが自動的に設定されます。`RealtimeSession` をバックエンド サーバー（例えば Node.js）で実行している場合、SDK は自動的に WebSocket を接続として使用します。異なるトランスポート層の詳細は、[リアルタイムトランスポート](/openai-agents-js/ja/guides/voice-agents/transport) ガイドをご覧ください。

6. **すべてを組み合わせる**

   <Code lang="typescript" code={helloWorldExample} />

7. **エンジンを起動して話し始める**

   Web サーバー を起動し、新しい リアルタイムエージェント のコードを含むページにアクセスします。マイクへのアクセス許可のリクエストが表示されます。許可すると、エージェントと会話を始められます。

   ```bash
   npm run dev
   ```

</Steps>

## 次のステップ

ここからは、独自の音声エージェントの設計と構築を始められます。音声エージェントには通常のエージェントと共通する機能が多くありますが、独自の機能も備えています。

- 音声エージェントに以下を追加する方法を学ぶ
  - [ツール](/openai-agents-js/ja/guides/voice-agents/build#tools)
  - [ハンドオフ](/openai-agents-js/ja/guides/voice-agents/build#handoffs)
  - [ガードレール](/openai-agents-js/ja/guides/voice-agents/build#guardrails)
  - [音声の割り込みの処理](/openai-agents-js/ja/guides/voice-agents/build#audio-interruptions)
  - [セッション履歴の管理](/openai-agents-js/ja/guides/voice-agents/build#session-history)

- 異なるトランスポート層の詳細を学ぶ
  - [WebRTC](/openai-agents-js/ja/guides/voice-agents/transport#connecting-over-webrtc)
  - [WebSocket](/openai-agents-js/ja/guides/voice-agents/transport#connecting-over-websocket)
  - [独自のトランスポートメカニズムの構築](/openai-agents-js/ja/guides/voice-agents/transport#building-your-own-transport-mechanism)
